docs: improve agent discoverability (README, AGENTS.md, llms.txt)#2588
docs: improve agent discoverability (README, AGENTS.md, llms.txt)#2588caio-pizzol merged 4 commits intosuperdoc-dev:mainfrom
Conversation
…s.txt Sharpen SuperDoc's positioning for AI agents evaluating DOCX editing tools. - README: rewrite tagline, add best-for/not-for filter, start-here routing table, expanded agent section with integration paths and use cases - AGENTS.md (package): restructure for agent evaluation — positioning, best-for/not-for, all integration paths, capability overview, knowledge corrections - llms.txt: new concise context file for AI crawlers with positioning, quick start, and links - llms-full.txt: comprehensive context with architecture, code examples, full operation list, and knowledge corrections Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
caio-pizzol
left a comment
caio-pizzol
left a comment
There was a problem hiding this comment.
@PeterHollens appreciate the effort here — adding llms.txt / llms-full.txt is something we've been wanting to do (SD-2319). a few things to address before merging.
headline: we're keeping "Modern document editing and tooling" for now. AI agents are a big focus for us but the headline needs to cover all SuperDoc use cases, not just agent workflows.
AGENTS.md: the current version has working code examples, a config table, and a "common tasks" cheat sheet — exactly what an AI agent needs when it finds this file in node_modules/. this rewrite replaces all of that with marketing-style content. i'd keep the current file as-is.
llms.txt files: great addition. the content needs a tone pass though — check brand.md for our voice guidelines. some of it reads more like a landing page than a technical reference. a couple factual fixes needed too (inline comments).
README.md: the "Best for / Not for" lists and new sections shift the tone from developer docs to product marketing. our brand leans toward "show, don't sell" — the current README structure works better.
suggested path: keep the llms files (with fixes + tone pass), drop the AGENTS.md and README changes, and use brand.md as the style guide.
|
Hey @PeterHollens, this PR has had no activity for 4 days. |
|
Correct yes I've been on OOO |
Drop README.md and AGENTS.md changes per reviewer feedback — keep
existing headline and code-example-rich AGENTS.md as-is.
llms.txt and llms-full.txt fixes:
- Use brand tagline ("The document engine for the modern web")
- Fix operation count: 360+ → 340+ (actual count is 344)
- Remove duplicate URL (AI agents guide listed twice)
- Tone pass per brand.md: technical reference voice, not landing page
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
@caio-pizzol thanks for the thorough review — all good calls. What changed:
PR now only adds the two llms files. Let me know if the tone still needs adjustment — happy to iterate. |
The Node.js SDK example used non-existent methods (blocks.list(), blocks.update()) and wrong parameter names (content instead of text). Replaced with the actual SDK API pattern from the SDK README.
caio-pizzol
left a comment
caio-pizzol
left a comment
There was a problem hiding this comment.
@PeterHollens the scope reduction to just the llms files is exactly right — all the round 1 feedback is addressed.
pushed a fix for the SDK code example in llms-full.txt — it used methods that don't exist in the SDK (blocks.list(), blocks.update(), wrong param name on comments.create). replaced with the actual API pattern from the SDK README.
one open question on the MCP tool count — left an inline comment. otherwise this is good to go.
The MCP server now registers 180+ individual tools (178 intent + 3 lifecycle) instead of the old 12 grouped tools. Update both llms.txt and llms-full.txt to reflect the current count.
caio-pizzol
left a comment
caio-pizzol
left a comment
There was a problem hiding this comment.
pushed fixes for the SDK example and MCP tool count. all good now — lgtm.
2 participants
Summary
Sharpens SuperDoc's positioning for AI agents evaluating DOCX editing tools. Four low-risk, additive changes:
Context
AI agents increasingly discover and evaluate tools by reading READMEs,
llms.txt, andAGENTS.mdfiles. These changes make it easier for an agent to conclude "SuperDoc is the right tool for real DOCX workflows" without reading multiple doc pages.Based on competitive analysis of Nutrient, CKEditor, Syncfusion, Apryse, OnlyOffice, and Microsoft Word MCP — SuperDoc has the strongest combination of OOXML-native editing, tracked changes, agent tooling, and self-hosted deployment. The gap is discoverability, not capability.
Test plan
AGENTS.mdcontent is accurate against current MCP/SDK capabilities🤖 Generated with Claude Code